home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / lan / apinst.zip / APINST.TXT next >
Text File  |  1994-04-05  |  16KB  |  404 lines
  1.  
  2.               NOVELL TECHNICAL INFORMATION DOCUMENT
  3.  
  4. TITLE:              AppWare Bullets Article (3/94) Source Code
  5. DOCUMENT ID:        TID100120
  6. DOCUMENT REVISION:  A
  7. DATE:               05APR94
  8. ALERT STATUS:       Yellow
  9. INFORMATION TYPE:   Symptom Solution
  10. README FOR:         APINST.EXE
  11.  
  12. NOVELL PRODUCT and VERSION:
  13. AppWare Foundation for Windows 1.70
  14.  
  15. ABSTRACT:
  16.  
  17. APINST.EXE contains the source code and the executable for the PDS Bullets
  18. article that was published in March 1994.
  19.  
  20. ──────────────────────────────────────────────────────────────────────────────
  21. DISCLAIMER
  22. THE ORIGIN OF THIS INFORMATION MAY BE INTERNAL OR EXTERNAL TO NOVELL.  NOVELL
  23. MAKES EVERY EFFORT WITHIN ITS MEANS TO VERIFY THIS INFORMATION.  HOWEVER, THE
  24. INFORMATION PROVIDED IN THIS DOCUMENT IS FOR YOUR INFORMATION ONLY.  NOVELL
  25. MAKES NO EXPLICIT OR IMPLIED CLAIMS TO THE VALIDITY OF THIS INFORMATION.
  26. ──────────────────────────────────────────────────────────────────────────────
  27.  
  28. SYMPTOM
  29.  
  30.      Users wanted the source code and the executable for the PDS Bullets
  31.      article that was published in March 1994.
  32.  
  33. SOLUTION
  34.  
  35.      APINST.EXE contains the source code and the executable for the PDS
  36.      Bullets article that was published in March 1994.
  37.  
  38.      Self-Extracting File Name:  APINST.EXE     Revision:  A
  39.  
  40.      Files Included     Size     Date      Time
  41.  
  42.      \
  43.        APINST.TXT         (This File)
  44.            APPF.R       4244   03-17-94   11:49a
  45.            MAIN.C       9353   03-17-94   12:49p
  46.            MAIN.H       2023   03-16-94    9:30a
  47.            MAIN.I      73668   03-17-94   11:57a
  48.            MAIN.R        579   02-16-94    3:02p
  49.            MAIN.Z       2465   03-17-94   12:49p
  50.           APP.EXE      25128   03-17-94   12:50p
  51.           APP.ICO        766   09-17-93   12:00a
  52.           MAIN.RC       2095   02-16-94    9:40a
  53.           MAINR.H       2943   03-16-94    9:30a
  54.          MAIN.BMK       2611   03-17-94   12:55p
  55.          MAIN.DEF        414   02-11-94    5:41p
  56.          MAIN.RES       1304   03-17-94   12:50p
  57.      DISCLAIM.TXT        977   07-15-91   12:30p
  58.  
  59.      Installation Instructions:
  60.  
  61.      No installation instructions are included with this file.
  62.  
  63.      Solution Specifics:
  64.  
  65.      The following the text of the Bullets article: "Loading the Application
  66.      Instance as a Resource"
  67.  
  68.      AppWare Foundation:
  69.      Loading the Application Instance as a Resource
  70.  
  71.      The Novell AppWare Foundation (NAWF) is the base component of the Novell
  72.      AppWare development architecture and is designed for developers who want
  73.      to code directly to the core component of the AppWare development
  74.      environment. NAWF is composed of programming libraries and a
  75.      cross-platform API for accessing operating system, user interface, and
  76.      connectivity services with traditional 3GL programming tools. NAWF is
  77.      divided into different components and the components are grouped into
  78.      series. Currently there are three series:
  79.  
  80.      *    Operating System
  81.      *    User Interface
  82.      *    Network Connectivity.
  83.  
  84.      The components are a collection of utility routines that are reusable
  85.      within and among applications. Components encapsulate their routines with
  86.      associated data elements, and some components rely on and inherit
  87.      capabilities from other components. These components are implemented as
  88.      modules using C.
  89.  
  90.      This article introduces the experienced C programmer to NAWF by detailing
  91.      a method for creating a generic NAWF application that loads the
  92.      Application instance as a resource. This resource can be used as a seed
  93.      for other NAWF applications.
  94.  
  95.      Instances
  96.  
  97.      Instances are complex entities with many characteristics and behaviors.
  98.      Instances are designed as general purpose entities, however all
  99.      instance-using NAWF components are from the User Interface Series and are
  100.      used to implement graphical user interfaces. They usually have a visible
  101.      representation on the screen and interact with the end-user. The
  102.      characteristics of instances include their types, attributes, and
  103.      relationships to one another.
  104.  
  105.      Instances can be created in two ways:
  106.  
  107.      *    By loading instance data into a structure invoking the NAWF
  108.           UInstCreate() function
  109.      *    By describing it in a NAWF superset resource file, compiling it
  110.           using the NAWFresource and compiler, and calling the UInstLoad()
  111.           function. This article demonstrateshow to load the Application
  112.           instance as a resource.
  113.  
  114.      As instances are created, they are organized into a hierarchy. At the top
  115.      of every instance hierarchy there is an Application instance.
  116.  
  117.      Having a generic NAWF application you can later use as a starting point
  118.      for other applications eases the process of adding functionality. If you
  119.      can load a simple NAWF application as a resource, it will be easy to port
  120.      that application to all other target operating system platforms.  Since
  121.      the Application instance is just another NAWF instance, you can edit it
  122.      using a resource editor.
  123.  
  124.      For example, you could set the Application instance style to "iconized"
  125.      by changing the attribute in the resource definition. To do this, you do
  126.      not have to recompile the C source modules. The change can be effected by
  127.      recompiling only the resources and then relinking the program.
  128.  
  129.  
  130.      Elements of a Generic NAWF Application
  131.  
  132.      Four types of files comprise a generic NAWF application:
  133.  
  134.      *    C Sources (.C)
  135.      *    Header (.H)
  136.      *    Intermediate include file (.Z)
  137.      *    Superset resource file (.R)
  138.  
  139.      Intermediate include files have a .Z extension and may include any number
  140.      of .h header files. All headers to be pre-compiled are gathered into the
  141.      .Z file. Intermediate include files are used only for source files that
  142.      are intended to be machine independent.
  143.  
  144.      Superset resource files have a .R file extension. Superset resources are
  145.      resources defined by a platform-independent resource definition language.
  146.      This language allows you to specify instance information that is a
  147.      superset of the resource information for all platforms. Superset instance
  148.      resources are described in text form in a resource data file.  The
  149.      instance resource contains a standard header followed by fields specific
  150.      to the instance type.
  151.  
  152.      Loading the Application instance as a resource requires four steps:
  153.  
  154.      *    Defining the application instance in the superset resource file
  155.      *    Making the NAWF component initializations in the C source file
  156.      *    Defining the appropriate vectors in the C source file
  157.      *    Loading the Application instance
  158.  
  159.  
  160.      Defining the Application Instance
  161.  
  162.      The Application instance is just another NAWF instance. Like all
  163.      instances, the application instance has common instance information and
  164.      specialized instance information. The code segment in Figure 1 defines
  165.      the Application instance in the superset resource file.
  166.  
  167. *****************************************************************
  168. Figure 1: Defining the Application instance in superset resource file
  169.  
  170. resource URES_TYPE_INSTANCE(APP_ID_KEY)
  171. {
  172.  
  173.    /* options, native ref, default font, device type, extra */
  174.  
  175.    UR_UNITS_CHARS | UR_RECT_FRAME, DataNone{}, DataNone {}, N_NULL, {},
  176.    {
  177.       InstApplication
  178.       {
  179.  
  180.          /* native key, resource options, childcount */
  181.  
  182.          0, UR_RECT_CONTENT, 0,
  183.  
  184.          /* action code, action params, user data, buf size, buf data */
  185.  
  186.          N_NULL, DataNone {}, N_NULL, 0, DataNone {},
  187.  
  188.          /* Filter */
  189.  
  190.          Filt {UINST_FOPT_VECTOR | UINST_FOPT_ALL,
  191.               { N_NULL, N_NULL,  N_NULL },
  192.               { N_NULL, N_NULL,  N_NULL },
  193.           "AppVector" },
  194.  
  195.          /* item type, data, attrs */
  196.  
  197.          TypeID{UITEM_ID_BASEFONT}, DataStr{ "App Instance" },
  198.                 AttrsNone{},
  199.  
  200.          /* Virtual Data */
  201.  
  202.          VirtNone{},
  203.  
  204.          /* style, style2, options, options2, alignment */
  205.  
  206.          UINST_STYLE_SHOW|UINST_STYLE_CLOSEABLE|
  207.             UINST_STYLE_ICONIZEABLE|UINST_STYLE_SIZEABLE,
  208.          N_NULL, N_NULL, N_NULL, N_NULL,
  209.  
  210.          /* frame, selection, mnemonic, cursor */
  211.  
  212.          RectNone , SelNone {}, MnNone {}, DataStd
  213.             {URES_STD_ARROW_CURS},
  214.  
  215.          /* help desc, help topic, extra */
  216.  
  217.          HelpNone{}, HelpNone{}, {},
  218.  
  219.          /* icon, menu bar, window menu position, size information */
  220.  
  221.          DataNone {},
  222.          DataRef {"",URES_TYPE_INSTANCE, APP_MENU, N_NULL},
  223.                   N_NULL, SizeNone {},
  224.  
  225.          /* foreground timer intervals, background timer intervals,
  226.             help config structure, extra */
  227.  
  228.          0, 0, HelpConfigNone {}, {}
  229.       },
  230.    }
  231. };
  232.  
  233. END of FIGURE 1
  234. *****************************************************************
  235.  
  236.      Initializing NAWF Components
  237.  
  238.      An important part of the application setup process is initializing each
  239.      NAWF component that will be used in the application. NAWF components must
  240.      be initialized in a strict order to be properly utilized by an
  241.      application. Failure to observe this requirement can cause erratic
  242.      application behavior such as a General Protection Fault in the NAWF.DLL
  243.      under MS Windows.
  244.  
  245.      The components listed in Figure 2 are shown in the proper sequence. 
  246.      Although only three components are listed, other components must be
  247.      initialized in proper order, depending on which ones you use in your
  248.      application.
  249.  
  250.  
  251. *****************************************************************
  252. Figure 2: NAWF component initialization
  253.  
  254. /* Essential foundation components */
  255.  
  256. if (! UModInit ( &Access, UMOD_VERSION, 0L ))
  257.     UModExit( UErrGetVal( &Access ) );
  258. if (! UMemInit ( &Access, UMEM_VERSION, 0L ))
  259.     UModExit( UErrGetVal( &Access ) );
  260. if (! UErrInit ( &Access, UERR_VERSION, 0L ))
  261.     UModExit( UErrGetVal( &Access ) );
  262.  
  263. /* Other component initializations */
  264.  
  265. END of FIGURE 2
  266. *****************************************************************
  267.  
  268.      Defining Message Vectors
  269.  
  270.      Before loading the Application instance, you must make sure that the
  271.      appropriate vectors are defined for the messages that you want to filter.
  272.  
  273.      Using vectors for message filtering is somewhat different than using
  274.      callback filters and explicit filter masks. Rather than writing a single
  275.      message filter procedure that handles all message types utilizing a
  276.      switch statement, you can write a set of individual message handlers. 
  277.      Each handler can be written to handle a specific message before or after
  278.      notification (pre- or post-notification). These handlers are then
  279.      associated with message types by a vector definition, shown in Figure 3.
  280.  
  281.      Note: UInstVectorBegin, UInstVectorMsg, and UInstVectorEnd are macros
  282.      with parameters which generate code. These macros must never be
  283.      terminated with semicolons.
  284.  
  285. *****************************************************************
  286. Figure 3: Associating message types  with a vector definition
  287.  
  288. /* Begin the vector definition */
  289.  
  290. UInstVectorBegin( AppVector, N_NULL )
  291.  
  292. /* Associate OnAppAfterCREATE filter procedure with the post-filtered
  293.    UMSG_CREATE message */
  294.  
  295. UInstVectorMsg( UMSG_CREATE, UMSG_MODE_AFTER, OnAppAfterCREATE)
  296.  
  297. /* Associate OnAppAfterACTION filter procedure with the post-filtered
  298.    UMSG_ACTION message */
  299.  
  300. UInstVectorMsg( UMSG_ACTION, UMSG_MODE_AFTER, OnAppAfterACTION)
  301.  
  302. /* End the AppVector definition */
  303.  
  304. UInstVectorEnd( AppVector )
  305.  
  306. END of FIGURE 3
  307. *****************************************************************
  308.  
  309.  
  310.      The code in Figure 3 associates two filter procedures with the
  311.      UMSG_CREATE and the UMSG_ACTION messages. The code segment in Figure 4
  312.      defines the OnAppAfterCREATE filter procedure that would automatically be
  313.      called when a post-filtered UMSG_CREATE message is generated.
  314.  
  315. *****************************************************************
  316. Figure 4: Defining the OnAppAfterCREATE filter procedure
  317.  
  318. N_GLOBAL_FUNC( nbool8 )
  319. OnAppAfterCREATE ( pUMsgStruct pMsg )
  320. {
  321.      /* You can put in the code that you want executed */
  322.  
  323.       return N_TRUE;
  324. }
  325.  
  326. END of FIGURE 4
  327. *****************************************************************
  328.  
  329.      Loading the Application Instance
  330.  
  331.      NAWF instances can either be created by calling UInstCreate(), or by
  332.      loading it as a resource by a call to the function UInstLoad(), as shown
  333.      below.
  334.  
  335.      nid UInstLoad (pAccess,
  336.                     idInstParent,
  337.                     idResPack,
  338.                     pInstFilter,
  339.                     userLoadData);
  340.  
  341.      UInstLoad() is used to load an instance or an instance hierarchy from a
  342.      resource definition. The example program discussed in this article uses
  343.      the UInstLoad() function to load the Application instance as a resource. 
  344.      The code segment below demonstrates how the Application instance must be
  345.      defined in the superset resource (.R) file.
  346.  
  347.      Assuming that you have performed the appropriate NAWF component
  348.      intializations, and have created the UModMain() function with the message
  349.      loop, you can add the function shown in Figure 5 to load the Application
  350.      instance as a resource.
  351.  
  352.  
  353. *****************************************************************
  354. Figure 5: Loading the Application instance
  355.  
  356. N_INTERN_FUNC( nid )     
  357. LoadApp( void )
  358. {
  359.    nid         idResPack, appID;
  360.  
  361.    /* Open resource file */
  362.    /* Access and idResFile are global variables */
  363.    idResFile = UResOpenModule( &Access, UModGetModule( &Access ),
  364.                                URES_OPEN_READ );
  365.    /* Initialize Application instance */
  366.    idResPack = UResCreatePack (&Access, idResFile, URES_TYPE_INSTANCE,
  367.                                APP_ID_KEY, URES_PACK_NO_KEEP);
  368.    DEBUG_ASSERT( UErrGetVal( &Access ) == N_SUCCESS &&
  369.                  UResValidatePack( &Access, idResPack ),
  370.                  "Can't reference App resource" );
  371.    /* Load the App instance from the resources */
  372.    appID = UInstLoad (&Access, N_NULL, idResPack, N_NULL, N_NULL);
  373.    return (appID);
  374. }
  375.  
  376. END of FIGURE 5
  377. *****************************************************************
  378.  
  379.  
  380.      Using a graphical resource editor, you can easily add additional NAWF
  381.      instances as "children" of the Application instance. These instances are
  382.      defined wholly in the resource file and only processing code need be
  383.      added to your program.
  384.  
  385.      If you would like to obtain the complete source code for the example
  386.      discussed in this article, it is available for downloading from Novell's
  387.      NOVLIB forum on CompuServe (Library 7, APINST.EXE).
  388.  
  389.      If you have additional questions about any of the concepts discussed in
  390.      this article or about the Novell AppWare Foundation, please contact
  391.      Novell at 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.
  392.  
  393.  
  394. *****************************************************************
  395. *****************************************************************
  396. (c) Copyright 1994 Novell, Inc. This article originally appeared in
  397. Novell Professional Developer Bullets, Volume 6, Number 3.
  398. *****************************************************************
  399. *****************************************************************
  400.  
  401.  
  402.  
  403.  
  404.